---
title: Layout
description: HeroUI offers a set of layout options to customize the theme.
---

# Layout

HeroUI provides layout customization options for spacing, fonts, and other visual properties. Layout tokens help maintain consistency across components without modifying Tailwind CSS defaults.

<CarbonAd/>

<Spacer y={4} />

```js {4,7,11}
module.exports = {
  plugins: [
    heroui({
      layout: {}, // common layout options
      themes: {
        light: {
          layout: {}, // light theme layout options
          // ...
        },
        dark: {
          layout: {}, // dark theme layout options
          // ...
        },
        // ... custom themes
      },
    }),
  ],
};
```

> Layout options are applied to all components.

## Default Layout

Default values for the layout tokens are:

```js
module.exports = {
  plugins: [
    heroui({
      layout: {
        dividerWeight: "1px", // h-divider the default height applied to the divider component
        disabledOpacity: 0.5, // this value is applied as opacity-[value] when the component is disabled
        fontSize: {
          tiny: "0.75rem", // text-tiny
          small: "0.875rem", // text-small
          medium: "1rem", // text-medium
          large: "1.125rem", // text-large
        },
        lineHeight: {
          tiny: "1rem", // text-tiny
          small: "1.25rem", // text-small
          medium: "1.5rem", // text-medium
          large: "1.75rem", // text-large
        },
        radius: {
          small: "8px", // rounded-small
          medium: "12px", // rounded-medium
          large: "14px", // rounded-large
        },
        borderWidth: {
          small: "1px", // border-small
          medium: "2px", // border-medium (default)
          large: "3px", // border-large
        },
      },
      themes: {
        light: {
          layout: {
            hoverOpacity: 0.8, //  this value is applied as opacity-[value] when the component is hovered
            boxShadow: {
              // shadow-small
              small:
                "0px 0px 5px 0px rgb(0 0 0 / 0.02), 0px 2px 10px 0px rgb(0 0 0 / 0.06), 0px 0px 1px 0px rgb(0 0 0 / 0.3)",
              // shadow-medium
              medium:
                "0px 0px 15px 0px rgb(0 0 0 / 0.03), 0px 2px 30px 0px rgb(0 0 0 / 0.08), 0px 0px 1px 0px rgb(0 0 0 / 0.3)",
              // shadow-large
              large:
                "0px 0px 30px 0px rgb(0 0 0 / 0.04), 0px 30px 60px 0px rgb(0 0 0 / 0.12), 0px 0px 1px 0px rgb(0 0 0 / 0.3)",
            },
          },
        },
        dark: {
          layout: {
            hoverOpacity: 0.9, //  this value is applied as opacity-[value] when the component is hovered
            boxShadow: {
              // shadow-small
              small:
                "0px 0px 5px 0px rgb(0 0 0 / 0.05), 0px 2px 10px 0px rgb(0 0 0 / 0.2), inset 0px 0px 1px 0px rgb(255 255 255 / 0.15)",
              // shadow-medium
              medium:
                "0px 0px 15px 0px rgb(0 0 0 / 0.06), 0px 2px 30px 0px rgb(0 0 0 / 0.22), inset 0px 0px 1px 0px rgb(255 255 255 / 0.15)",
              // shadow-large
              large:
                "0px 0px 30px 0px rgb(0 0 0 / 0.07), 0px 30px 60px 0px rgb(0 0 0 / 0.26), inset 0px 0px 1px 0px rgb(255 255 255 / 0.15)",
            },
          },
        },
      },
    }),
  ],
};
```

### CSS Variables

HeroUI creates CSS variables using the format `--prefix-prop-name-scale` for each layout token. By
default the prefix is `heroui`, but you can change it with the `prefix` option.

```js {4}
module.exports = {
  plugins: [
    heroui({
      prefix: "myapp",
    }),
  ],
};
```

Then you can use the CSS variables in your CSS files.

```css
/* With default prefix */
.my-button {
  font-size: var(--heroui-font-size-small);
  line-height: var(--heroui-line-height-small);
  border-radius: var(--heroui-radius-medium);
}

/*  With custom prefix */
.my-component {
  font-size: var(--myapp-font-size-small);
  line-height: var(--myapp-line-height-small);
  border-radius: var(--myapp-radius-medium);
}
```

#### API Reference

| Attribute       | Type                            | Description                                                                                 |
| --------------- | ------------------------------- | ------------------------------------------------------------------------------------------- |
| hoverOpacity    | string, number                  | A number between 0 and 1 that is applied as opacity-[value] when the component is hovered.  |
| disabledOpacity | string, number                  | A number between 0 and 1 that is applied as opacity-[value] when the component is disabled. |
| dividerWeight   | string                          | The default height applied to the divider component. We recommend to use `px` units.        |
| fontSize        | [FontThemeUnit](#fontthemeunit) | The default font size applied across the components.                                        |
| lineHeight      | [FontThemeUnit](#fontthemeunit) | The default line height applied across the components.                                      |
| radius          | [BaseThemeUnit](#basethemeunit) | The default radius applied across the components. We recommend to use `rem` units.          |
| borderWidth     | [BaseThemeUnit](#basethemeunit) | The border width applied across the components.                                             |
| boxShadow       | [BaseThemeUnit](#basethemeunit) | The box shadow applied across the components.                                               |

#### BaseThemeUnit

```ts
export type BaseThemeUnit = {
  small?: string;
  medium?: string;
  large?: string;
};
```

#### FontThemeUnit

```ts
export type FontThemeUnit = {
  small?: string;
  medium?: string;
  large?: string;
  tiny?: string;
};
```